


/-------------------------------------------------------------------------------------------------------------\
|                                                                                                             |
| LIBRERIA upcTV V1.0                                                                                         |
| Copyright  Universitat Politcnica de Catalunya                                                            |
|                                                                                                             |
| Grup de Tractament de la Parla           http://gps-tsc.upc.es/veu                                          |
| Universitat Politecnica de Catalunya     http://www.upc.es                                                  |
|                                                                                                             |
| Profesor responsable del proyecto:       Antonio Bonafonte                                                  |
|                                          antonio@gps.tsc.upc.es                                             |
|                                                                                                             |
|                                          Telef. 93 401 6457                                                 |
|                                          Fax    93 401 6447                                                 |
| Febrero 1999                                                                                                |
|                                                                                                             |
\-------------------------------------------------------------------------------------------------------------/



Este documento consta de los siguientes apartados:

A) Descripcion de los ficheros que se entregan
B) Descripcion de las funciones desarrolladas
C) La plantilla de WORD
D) Discusion. Cambios respecto version beta y futuros cambios.



*****************************************************************************************************************
A) Descripcion de los ficheros que se entregan
*****************************************************************************************************************

La libreria upcTV es un lector de textos en castellano y catalan para Windows 32 bits, concretamente
Windows 95 y Windows NT.

En la entrega se incluye:

0) Este fichero, leeme.txt, documentacion de la libreria

1) La libreria:
   upctv.dll

2) Un directorio de datos que aparece con el nombre Dat. En este directorio aparecen unos ficheros de texto
   (extension .txt) que son diccionarios de acronimos y abreviaturas que pueden editarse y cambiarse a voluntad
   (por ejemplo para incluir ESO, PIE, etc. si se desea que se lean de otro modo). Los sufijos _sp significan
   castellano mientras que _ct significan catalan.

   En el mismo directorio aparece el fichero upctv.reg que ha de utilizase para que funcione la libreria.
   En primer lugar:
      - Editar el fichero (seleccionar fichero; boton de la derecha; editar) para poner el path donde se
        encuentra la carpeta Dat; de hecho un fichero de esa carpeta llamado ttscnf.etq
      - Incluir la informacion en el registro: doble click en el fichero.

3) Los fichero upctv.h y upctv.lib con las definiciones de las funciones por si se quieren llamar 
   mediante enlace estatico.

4) Un programa escrito en "C", tv.exe, que utiliza la libreria para leer texto. Se adjunta tambien
   el codigo en "C" tv.cpp como un ejemplo de uso de la libreria.
   Tambien se incluye el fichero Language.h que contiene la definicion de los codigos que hay que pasar
   a la funcion que cambia el idioma de la lectura para que lo haga en castellano o en catalan.

   Nota: para que funcione el programa tts.exe es necesario que la libreria upctv este en un directorio del path:
   el directorio del propio programa, el directorio de windows o el del sistema, etc.

   El programa puede ejecutarse sin argumentos o bien con una lista de ficheros para leer. 
   Ejemplo:
   tv fichero_catellano.txt fichero_catalan.txt

   En este caso, cada vez que se seleciona la opcion de lectura se pasa al fichero siguiente.

5) Una plantilla de MS-WORD 97, upcTV.dot, que utiliza la libreria para leer documentos de word. Se debe copiar
   la plantilla en el directorio de plantillas de word (que puede verse desde word mediante el menu 
   herramientas -> opciones, en la pestanya de directorio de ficheros (o algo asi).
   La libreria upctv.dll ha de estar en un directorio del path de word, por ejemplo, en el directorio
   del sistema de windows.
   Una vez instalada, abrir un nuevo fichero mediante el menu Fichero->nuevo y seleccionar la plantilla upcTv.
   El objetivo de esta plantilla es solo mostrar como funciona la libreria pero no es una plantilla definitiva.
   En particular, el tema de seleccion del locutor esta muy mal tratado: no muestra los locutores que hay
   sino que solo permite pasar al siguiente locutor, etc.


*****************************************************************************************************************
B) Descripcion de las funciones desarrolladas
*****************************************************************************************************************
 

El fichero upctv.h contiene la declaracion de las funciones que creo que es de por si bastante explicito.


FICHERO UPCTV.H
------------------------------------------------------------------------------------
#ifndef UPCTV_H
#define UPCTV_H

extern "C" int __stdcall  upcTVAbout();
extern "C" int __stdcall  upcTVRead (const char *String);
extern "C" int __stdcall  upcTVReadFile(const char *FileName);
extern "C" int __stdcall  upcTVStop();
extern "C" int __stdcall  upcTVPause();
extern "C" int __stdcall  upcTVResume();

extern "C" int __stdcall  upcTVSetSpeaker(unsigned short spkId);
extern "C" int __stdcall  upcTVSetSpeed(unsigned short WordsPerMinute);
extern "C" int __stdcall  upcTVSetLanguage(short Lang);
extern "C" int __stdcall  upcTVGetNumberOfSpeakers ();
extern "C" int __stdcall  upcTVGetInfoSpeaker(unsigned short spkId, char *buff, unsigned long buffSize);

------------------------------------------------------------------------------------
#endif


Al cargarse la libreria se realizan todas las inicializaciones necesarias para utilizar el conversor.
Los recursos son liberados cuando se descarga la libreria. Todos los parametros (en particular char *) se
utilizan siguiendo el convenio de "C".

Funciones asincronas
upcTVRead	Lee el texto que se le pasa por parametro 
upcTVReadFile	Lee el fichero que se le pasa por parametro


Funciones sincronas
upcTVAbout	Muestra un cuadro de dialogo con informacion de la UPC. Quiza se deberia incluir la direccion
		del PIE para atender a los usuarios, informacion sobre la licencia de uso.
upvTVStop	Para de leer una frase. (No es posible ocntinuar)
upcTVPause	Para de leer una frase. Se puede continuar utilizando upcTVResume o bien para con Stop o 
		empezar a leer otro texto con alguna de las funciones Read
upcTVResume	continuar la lectura de una frase que se ha interrumpido mediante Pause
upcTVSetSpeaker	Cambiar al locutor 'i' (entre 0 y el numero de locutores -1)
upcTVSetSpeed	Fija la velocidad en numero de palabras por minuto (aproximado)
upvTVSetLanguage
		Permite fijar el idioma en que se leera el texto. En este momento el codigo que se utiliza
		esta definido en el fichero Language.h
upcTVGetInfoSpeaker
		Da informacion del locutor con identificativo 'i'. Un ejemplo:
		[ct sp], 2, 30, Josep

		- Entre corchetes, las lenguas que habla
		- a continuacion un 1 para mujer, 2 para hombre
		- despues la edad (aprox.) 30 anyos, adulto
		- finalmente el nombre que le damos al locutor. El identificativo de un locutor puede
                  cambiar en sucesivas entregas, pero no su nombre.


Todas las funciones devuelven un valor nulo cuando no ha ocurrido ningun error.


*****************************************************************************************************************
C) La plantilla de WORD upcTV.dot
*****************************************************************************************************************

upcTv.dot es una plantilla de Word que contiene un conjunto de macros que implementan las distintas 
funciones. La declaracion de las funciones y la inicializacion de algunas variables se encuentra en el modulo
AutoNew. Alli se fija el locutor y la lengua de inicio.





*****************************************************************************************************************
D) Discusion, cambios respecto a la version beta y futuros cambios
*****************************************************************************************************************

Para leer un texto es preciso especificar la lengua (catellano o catalan). 
La lengua prima sobre el locutor. Por tanto,
* Si se selecciona una lengua y el locutor actual no la habla, se cambiara de locutor.
* Si se selecciona un locutor que no hable la lengua seleccionada, se ignora la seleccion.


En esta version (pero no se asegura que se mantenga) la lengua por defecto es catalan.
En la plantilla Word se cambia este comportamiento utilizando las funciones al abrir la plantilla de forma
que a priori se leera en castellano.


No puede cambiarse de locutor mientras se esta leyendo un texto. Es necesario parar y proceder al cambio.
La opcion de cambio de velocidad tiene un efecto retardado ya que parte del texto a leer se ha procesado.
Se aconseja no permitir que el usuario las utilice mientras se esta leyendo, al menos no de forma relativa,
como en los dos ejemplos sino en todo caso valor absoluto: numero de palabras por minuto, un control 
graduable entre un maximo y un minimo, etc.


En la proxima version de la libreria se permitira controlar el texto mediante palabras de control dentro del
texto. El lenguaje de control sera SABLE del que puede encontrarse informacion en:

http://www.cstr.ed.ac.uk/projects/ssml.html
De hecho, mas concretamente en
http://www.cstr.ed.ac.uk/projects/sable_spec2.html


Esta version soporta solo algunas funcionalidades de Sable pero no se recomienda su utilizacion.
Si tiene alguna consulta sobre el tema puede consultar a la direccion consignada.


En esta version ha sido desarrollada especificamente para ser distribuida en la aplicacion Sinera en Disc.
La primera vez que un usuario utiliza este lector aparece un cuadro de dialogo indicando las condiciones 
de uso. 


Nota: La libreria upcTV descansa a su vez sobre la libreria upcTTS, utilizada en varios entornos y aplicaciones. 
La mayor parte de la informacion que pueda encontrarse sobre upcTTS es tambien valida para upvTV.
